CoBra DEVIL raw floppy image reader / writer for Linux
CREATED BY: CoBra @ RomanianHomeComputer

This is a program with a dual behaviour: it can be used as a bash command-line-only utility (no GUI will be shown) or it can be used as a GUI and achieve the same things as in command line, and more.

In order to use it as a command line utility (in a bash console or a console window using bash as shell), it needs at least 2 arguments, which will have to be valid, recognized parameters as described next.

If less than 2 arguments are provided on the command line, or if the program is launched by clicking on the executable from a file manager, the GUI will be shown. If the GUI is launched from a console, useful information will be displayed in it during execution.

PURPOSE OF THIS PROGRAM

This program can manipulate DEVIL floppy image files (DEVIL is a version of Spectrum BASIC modified to work on CoBra computers using floppy disks) and .TAP files (files containing ZX Spectrum data in audio tape format). It was created to make it easier for Linux users to handle data for CoBra computers having an HxC floppy drive emulator installed in place of a physical floppy drive.

It can read and write RAW FORMAT floppy disk images of DSDD 720K CoBra DEVIL disks with 80 tracks, 18 sectors/track/side (36 sectors/track) and 256 bytes/sector, and displays a detailed DEVIL catalogue listing. These RAW floppy images can then be converted to .HFE floppy image files used directly by the HxC emulator instead of a physical floppy disk. This program also reads, creates and edits files in .TAP format, storing contents of ZX Spectrum software audio tapes.

Before going any further, I will define a few terms used next:

Directory: the first 3 tracks (0, 1 and 2) of the DEVIL floppy disk, containing - in each 256-byte sector - allocation information for the software stored on disk. These 3 tracks contain 36 x 3 = 108 sectors in total. Of these, only the first 77 sectors are used for the directory, and they are associated, in order, to one of the rest of 77 tracks of the disk. The allocation unit therefore is a full track (9 KB). So sector 1 of track 0 side 0 is associated with track 3 (both sides), sector 2 of track 0 side 0 is associated with track 4 (both sides), and so on. The last 31 sectors of track 2 are never used.
Directory entry: one of the 77 records in the DEVIL floppy disk directory, each taking up the first 18 bytes of a 256-byte sector in the directory. Each distinct directory entry represents one distinct data track (from track 3 to track 77) on disk
Catalog: the logical data structure extracted from the directory, containing individual data blocks as stored on original Spectrum audio data tape. One data block can take up multiple directory entries. The original Spectrum data tape format can store data blocks fully described by a preceding header block, and can also contain data blocks without any header (headerless data blocks). The DEVIL catalog can only store Spectrum data blocks preceded by a header block. IN GENERAL, headerless data blocks CANNOT BE STORED by the DEVIL disk catalog, since information like loading address for the block or start address of variable area is unknown and each catalog entry MUST specify this information. There is one exception to this rule: if one or more (up to 116) headerless data blocks (with a flag byte value of FFh) follow (one after another) immediately after a standard block (Prog, C Array, N Array or Code), they can be stored on disk immediately after the end of the standard block, taking up as many extra following disk tracks as needed.
Catalog entry: one individual data block stored on the DEVIL floppy image, as listed by the List command of this utility or by the STAT utility running under the DEVIL operating system. Spectrum data blocks (preceded by a header block) stored in the DEVIL catalog only show up with one entry (the data block itself), because the information in the header block is stored in the directory entries associated with that catalog entry. PLEASE NOTE: one catalog entry can occupy multiple directory entries, if the catalog entry contains data exceeding 9 KB in size, because the allocation unit on the DEVIL disk is one track (9 KB) and each allocation unit is associated with exactly one directory entry.

This utility can extract selected DEVIL catalogue entries from the floppy image into a .TAP file on your Linux filesystem.

It can also add (insert) the contents of a .TAP file (existent in your Linux filesystem) into the DEVIL catalog of the floppy image.

It can delete, rename, change attributes of DEVIL catalog entries stored in the floppy disk image.

It can create empty floppy images to which new catalog entries can then be added from existing .TAP files.

FLOPPY IMAGE FILE FORMAT USED BY THIS PROGRAM

The floppy image file contains 256-byte sectors saved with a physical interleave factor of 2, starting with sectors on side 0 of a track and continuing with sectors on side 1 of it. Formatting information is not stored in the floppy image, only the raw data.

The physical sector order (on each side of a track) is 1, 10, 2, 11, 3, 12, 4, 13, 5, 14, 6, 15, 7, 16, 8, 17, 9, 18, and their logical order (in which they are read/written) is 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18.

All tracks are saved like this, in their physical order (track 0, track 1 ... track 79).

This format is the same for all tracks, including 0, 1 and 2 (directory tracks containing the DEVIL catalog). The disk has 80 tracks, therefore all DEVIL floppy images have a fixed size of 737280 bytes (720 KB).

STRUCTURE OF A DEVIL DISK DIRECTORY ENTRY

DIRECTORY ENTRY STRUCTURE
=========================

Each directory entry takes up the first 18 bytes of each of the first 77 sectors on disk.
The last 179 bytes in each of these sectors are unused (are all zeros).

|<---------------------------------------------- one directory sector ----------------------------------------------->|

  00   01   02   03   04   05   06   07   08   09   10   11   12   13   14   15   16   17      18   19   20        255
+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+  +----+----+----+    +----+
| TY | N0 | N1 | N2 | N3 | N4 | N5 | N6 | N7 | N8 | N9 | D0 | D1 | A0 | A1 | B0 | B1 | SY |  | 00 | 00 | 00 | .. | 00 |
+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+  +----+----+----+    +----+

|<---------------------------------- one directory entry -------------------------------->|  |<---- unused bytes ---->|


Field meanings:
---------------

TY = DATA TYPE: 00 = program,
		01 = number array,
		02 = character array,
		03 = code,
		E4 = 2nd or later directory entry for same catalog entry,
		E5 = deleted directory entry)

N0...N9 = DATA BLOCK NAME (10 characters, padded with trailing blanks)

D0 = DATA BLOCK LENGTH (Low byte)	A0 = PARAMETER 1 (Low byte)	B0 = PARAMETER 2 (Low byte)
D1 = DATA BLOCK LENGTH (High byte)	A1 = PARAMETER 1 (High byte)	B1 = PARAMETER 2 (High byte)

SY = R/W-R/O, DIR-SYS ATTRIBUTES:	SY bit 1 = 0 FOR R/W,	SY bit 0 = 0 FOR DIR
						SY bit 1 = 1 FOR R/O	SY bit 0 = 1 FOR SYS

.TAP FILE FORMAT (USED BY ANY ZX SPECTRUM EMULATOR)

.TAP files contain sequences of binary data blocks, each block always starting with 2 bytes containing the length of data following.
The data following the 2-byte length always starts with a flag byte and ends with a checksum byte.
The checksum is calculated for all data bytes starting with the third byte (flag byte) in the block and ending with the last byte before the checksum byte.

HEADER BLOCK STRUCTURE
======================

              ______________Header block size (lower byte), always = 13
             /   ___________Header block size (upper byte), always = 00
            /   /   ________Flag byte (00 for headers)
           /   /   /   _____First byte of header (data type, 0 = Program, 1 = Numeric array, 2 = Character array, 3 = Code
          /   /   /   /
         /   /   /   /                                           ______________________Data length (lower byte)
        /   /   /   /                                           /   ___________________Data length (upper byte)
       /   /   /   /                                           /   /   ________________Parameter 1 lower byte (Start Addr lower half for Code)
      /   /   /   /                                           /   /   /   _____________Parameter 1 upper byte (Start Addr upper half for Code)
     /   /   /   /                                           /   /   /   /   __________Parameter 2 lower byte (00 for Code)
    /   /   /   /                                           /   /   /   /   /   _______Parameter 2 upper byte (80 for Code)
   /   /   /   /                                           /   /   /   /   /   /   ____Header XOR checksum (HFL to P21)
  /   /   /   /                                           /   /   /   /   /   /   /
 /   /   /   /  |------ file name blank padded -------|  /   /   /   /   /   /   /
HS0 HS1 HFL HTY N01 N02 N03 N04 N05 N06 N07 N08 N09 N10 DL0 DL1 P10 P11 P20 P21 HCK
        |---------------------- Spectrum-generated data --------------------------|

Header fields dependent on data type
====================================


 Data
Type 	   Parameter #1 	Parameter #2  Comments
 	   P10 	P11 		P20  P21  

 Program  Autostart Line ^* 	Var area offset  ^* 0 ... 9999 or 0x8000 if no autostart  
 Numeric Array  0x00  Var Name ^** 	0x00  0x80  ^** (1..26 meaning A..Z) + 128  
 Char Array  0x00  Var Name ^*** 	0x00  0x80  ^*** (1..26 meaning A..Z) + 192  
 Code  Loading Address 	0x00  0x80   




DATA BLOCK STRUCTURE
====================

       _______________Data block length (lower byte)
      /   ____________Data block length (upper byte)
     /   /   _________Flag byte (FF for data blocks)
    /   /   /
   /   /   /                           _____Data block checksum (DBF to Dxx)
  /   /   /                           /
 /   /   /  |----- user data -----|  /
DB0 DB1 DBF D00 D01 D02 D03 ... Dxx DCK

As you can see, the header block is a just particular case of data block, which is used to store information about the data block following after the header block.

COMMAND LINE SYNTAX DESCRIPTION

All command line parameters to this program must be given in the EXACT order specified in the command descriptions.
The general command line syntax for this program is:

/path/to/executable	command	/path/to/devildisk.img	...
	arg#1	arg#2	arg#3 ...

where "executable" is the name of this Linux program.

The first argument (arg#1) must always be a command (a dash followed by one or two letters).

The second argument (arg#2) must always be the path to the floppy image being processed. There is one exception, the ".TAP list" command, whose second argument must be the path to a .TAP file.

Command letters used are always in lowercase.
Accepted commands are:

Command	Command purpose
-c	Create an empty formatted floppy image (all sectors filled with the E5 byte)
-l	Display the detailed contents of the floppy image file
-x	Extract a specified range of catalog entries from the floppy image, to a directory having the name of the floppy image file (minus the .img extension), in a .TAP file.
-w	Write the contents of a .TAP file given by arg#3 into the floppy image.
-d	Delete the range of catalog entries specified by arg#3, from the floppy image
-g	Defragments the free space on the floppy image specified by arg#2.
-r0	Mark all catalog entries in the range specified by arg#3 as R/W.
-r1	Mark all catalog entries in the range specified by arg#3 as R/O.
-s0	Mark all catalog entries in the range specified by arg#3 as DIR.
-s1	Mark all catalog entries in the range specified by arg#3 as SYS.
-i	Interleave sectors on floppy image specified by arg#2. This floppy image must have a .dimg extension. The resulting floppy image is saved with the same name in the same directory but an .img extension.
-di	De-interleaves sectors in the floppy image specified by arg#2. The resulting floppy image is saved with the same name but a .dimg extension, in the same directory.
-t	List the contents of the .TAP file specified by arg#2.

CONSOLE COMMAND DESCRIPTIONS

In the following command descriptions, "executable" represents the name of this program, however you decide to name it after compilation. Note it is called as "/path/to/executable", meaning you don't necessarily have to run it from the same directory it is located in.

Every occurence of "/path/to/" in these descriptions denotes an absolute or relative path, whichever you want to use.

CREATE EMPTY FLOPPY IMAGE (-c)

Syntax:

/path/to/executable -c /path/to/devildisk.img

Creates an empty, formatted floppy image (all sectors filled with E5 bytes).

The executable can be run from a different directory than where it is located.

The second command line argument (/path/to/devildisk.img) is the path to the floppy image file being created.
If only the file name is given (no path is specified), the floppy image will be created in the current directory where the command is run.

The file name must end with an .img extension.

LIST FLOPPY IMAGE CONTENTS (-l)

Syntax:

/path/to/executable -l /path/to/devildisk.img [-deb]

Lists the contents of the floppy image, printing the following details for each catalog entry:

Index number
Data block type ("Prog" for BASIC programs, "NArr" for numeric arrays, "CArr" for character arrays or "Code" for code blocks)
Data block name
Data block length in bytes.
Start line if block type is "Prog" or start (loading) address if block type is "Code".
Offset of variable storage area from beginning of program (only if block type is "Prog").
Name of array variable (only if block type is "NArr" or "CArr").
Disk attributes for data block. There are 2 attributes: the first is either R/W or R/O, the second is either DIR or SYS.

Aside from these details, some disk totals will also be printed:

Number of directory entries used.
Number of directory entries available.
Total data size on disk in bytes, as sum of data lengths for all data blocks stored.
Total space occupied on disk in bytes (multiple of allocation unit size, 9 KB)
Total number of files (Devil catalog entries) on disk.
Disk free space (multiple of allocation unit size, 9 KB)

Also a short explanation is displayed for names used in the listing header.

The optional parameter -deb (debug) will list some extra low-level information:

A hex dump of the entire directory (the 18 bytes of each directory entry, of which the 10 bytes of the name will be displayed as ASCII;
A directory allocation table having a "1" for each allocated entry and a "0" for each available (unused) entry.

EXTRACT DEVIL CATALOG ENTRIES FROM FLOPPY IMAGE (-x)

Syntax:

/path/to/executable -x /path/to/devildisk.img range [-log|-ver [-deb]]

Extracts the catalog entries within the range specified by arg#3 ("range") from the floppy image and saves them in a .TAP file in the Linux filesystem.

The third argument ("range") can be a single index number or two index numbers separated by a dash. The index numbers to use are those listed by the -l command.
If one number is used, one single catalog entry (matching that index number) will be extracted. Otherwise the first index number must be less than the second and all catalog entries from the first index number to the second will be extracted.

The executable can be run from a different directory than where it is located.

Regardless of where this command is run from, a subdirectory named after the floppy image (without the .img extension) will be created (if not already existing) in the current directory where this command is executed.
The catalog entries will be extracted to a .TAP file, which will be saved in this newly created subdirectory.
The .TAP file will be named after the first catalog entry whose index number is specified by the "range" argument.
If a .TAP file with the same name already exists, it will be deleted first.

A 4th optional argument can be specified as either "-log" or "-ver".

The "-log" (save log) argument will create an extraction log file for every DEVIL catalog entry extracted and save the log in the same place as the .TAP file.

The "-ver" (verbose) argument will print the same details included in the log file to the console instead of saving them to the log file.

Only one of these 2 arguments can be used in a command (as the 4th argument).

Below are two examples of console output of extract operations, in normal mode (left) and in verbose mode (right).

Extracting data in normal mode.	Extracting data in verbose mode.

WRITE (ADD) CATALOG ENTRIES TO FLOPPY IMAGE (-w)

Syntax:

/path/to/executable -w /path/to/devildisk.img /path/to/tapfile.tap [-ver [-deb]]

Write the contents of the Linux file given by arg#3 ("/path/to/tapfile.tap") into the floppy image, as DEVIL catalog items. Here, the third argument ("/path/to/tapfile.tap") is the (absolute or relative) path of a .TAP file existing in your Linux filesystem.

A 4th optional argument can be specified as "-ver" (verbose). This will print extra details to the console during command execution.

Below are two examples of console output of write operations, in normal mode (left) and in verbose mode (right).

Writing data in normal mode.	Writing data in verbose mode.

DELETE DEVIL CATALOG ENTRIES FROM FLOPPY IMAGE (-d)

Syntax:

/path/to/executable -d /path/to/devildisk.img range [-ver [-deb]]

Delete the catalog entries within the range specified by arg#3 ("range"), from the floppy image file.

The third argument ("range") can be a single index number or two index numbers separated by a dash. The index numbers to use are those listed by the -l command.
If one number is used, one single catalog entry (matching that index number) will be deleted. Otherwise the first index number must be less than the second and all catalog entries from the first index number to the second will be deleted.

A 4th optional argument can be specified as "-ver" (verbose). This will print extra details to the console during command execution.

Below are two examples of console output of delete operations, in normal mode (left) and in verbose mode (right).

Deleting data in normal mode.	Deleting data in verbose mode.

If and only if the 4th argument is used, a 5th argument can optionally be used: "-deb" (debug). This will print the same low-level extra information to the console as mentioned for the -l command.

The deletion implemented here is a full and complete deletion, all directory records being deleted as well as their blocks alocated on disk will be filled with the E5 byte, not just the first byte in the directory records. Therefore, once a file has been deleted from the floppy image, it cannot be recovered anymore.

When deleting a range of catalog entries, a data gap (disk free space) may be left on the floppy image. Since Devil reads the floppy disk sequentially (basically the same way as a regular Spectrum audio tape) it is recommended that the free space on the floppy image be kept defragmented. This way, a subsequent write to the floppy image has more chances of finding a big enough continuous free space available for new data. When writing data to the floppy image (from a .TAP file containing Spectrum tape data blocks), this program will try and keep all data blocks being written in consecutive order. If this is not possible due to the free space being fragmented, the write operation will not take place.

In order to defragment the free space after a delete (-d) command, the defragment (-g) command can be used.

DEFRAGMENT FREE SPACE ON FLOPPY IMAGE (-g)

Syntax:

/path/to/executable -g /path/to/devildisk.img range [-ver [-deb]]

Defragment the free space on the floppy image, if allocated disk space is not continuous (i.e. after any catalog items have been deleted).

Below are two examples of console output of defragment operations, in normal mode (left) and in verbose mode (right).

Defragmenting data in normal mode.	Defragmenting data in verbose mode.

CHANGE ATTRIBUTES OF CATALOG ENTRIES ON FLOPPY IMAGE (-r0, -r1, -s0, -s1)

Syntax:

/path/to/executable -r0|-r1|-s0|-s1 /path/to/devildisk.img range [-ver [-deb]]

Modifies the attributes of the catalog entries within the range specified by arg#3 ("range").

Each catalog entry on a DEVIL floppy disk has 2 attributes: write mode access and visibility.
If the writing attribute is "R/W", the entry can be written/erased, if it is "R/O", it can only be read.
If the visibility attribute is "DIR", the entry will be listed by the CAT command in DEVIL, if it is "SYS" it will not.

These two attributes can be modified with the following commands:

-r0	Mark all catalog entries in the range specified by arg#3 as R/W.
-r1	Mark all catalog entries in the range specified by arg#3 as R/O.
-s0	Mark all catalog entries in the range specified by arg#3 as DIR.
-s1	Mark all catalog entries in the range specified by arg#3 as SYS.

The third argument ("range") can be a single index number or two index numbers separated by a dash. The index numbers to use are those listed by the -l command.
If one number is used, one single catalog entry (matching that index number) will be extracted. Otherwise the first index number must be less than the second and all catalog entries from the first index number to the second will be extracted.

A 4th optional argument can be specified as "-ver" (verbose). This will print extra details to the console during command execution.

Below are two examples of console output of attribute change operations, in normal mode (left) and in verbose mode (right).

Attribute change in normal mode.	Attribute change in verbose mode.

INTERLEAVE FLOPPY IMAGE (-i)

Syntax:

/path/to/executable -i /path/to/devildisk.dimg [-ver]

As mentioned at the beginning, this program operates on RAW floppy images with a sector interleave factor of 2. Other conversion software (like the HxC Floppy Emulator software) save RAW floppy images without any interleaving.

This command will take a non-interleaved RAW floppy image saved by other software (arg#2), which will need to have a ".dimg" extension, and convert it to an interleaved format recognized by this program. The result is saved in a new floppy image with the same file name and an ".img" extension, in the same directory with the ".dimg" file. That means the directory containing arg#2 must have writing access for your user.

A 3rd optional argument can be specified as "-ver" (verbose). This will print extra details to the console during command execution.

Below are two examples of console output of interleave commands, in normal mode (left) and in verbose mode (right).

Interleave command in normal mode.	Interleave command in verbose mode.

DE-INTERLEAVE FLOPPY IMAGE (-di)

Syntax:

/path/to/executable -di /path/to/devildisk.img [-ver]

As mentioned at the beginning, this program operates on RAW floppy images with a sector interleave factor of 2. Other conversion software (like the HxC Floppy Emulator software) save RAW floppy images without any interleaving.

This command will take an interleaved RAW floppy image recognized by this program (arg#2), and convert it to a non-interleaved format used by other software. The result is saved in a new floppy image with the same file name and a ".dimg" extension, in the same directory with the ".img" file. That means the directory containing arg#2 must have writing access for your user.

A 3rd optional argument can be specified as "-ver" (verbose). This will print extra details to the console during command execution.

Below are two examples of console output of deinterleave commands, in normal mode (left) and in verbose mode (right).

Deinterleave command in normal mode.	Deinterleave command in verbose mode.

LIST .TAP FILE CONTENTS (-t)

Syntax:

/path/to/executable -t /path/to/tapfile.tap [-ver]

Lists the contents of the .TAP file, printing the following details for each block found.

If the optional parameter -ver is used, extra details are printed about the number of floppy disk tracks required for each .TAP data block, in case the contents of the .TAP file is to be transferred to a DEVIL floppy image:

.TAP file list command in normal mode.	.TAP file list command in verbose mode.

Data format (column "Form"), which can be a header ("Head") describing the following block, or plain data ("Data").
Error (if any) found in the current block (column "E"). This is a single character meaning:
- " " - (space), no error found
- "!" - wrong checksum byte for current block
- "?" - unexpected end of file - cannot read the 2-byte data length of current block
- "*" - unexpected end of file - missing end of current block
Block index number in the .TAP file (column "T#"), as a 4-digit decimal value. Every block in the .TAP file has an index number matching its order within the file.
Block order number if written to a DEVIL floppy image (column "D#"), as a 4-digit decimal value. Only data blocks preceded by a header block will have this number. This basically gives a count of data blocks that can theoretically be written to a DEVIL floppy image.
Flag byte (column "Flag") as a 2-digit hex value.
Block length in bytes (column "Size") as a decimal value, excluding the first 2 bytes containing the data length, but including the flag byte and the checksum byte.
Data type (column "Type"). This can be a program ("Prog"), numeric array ("NArr"), character array ("CArr") or code ("Code").
Only shown in header blocks.
Name (column "Name"). This is the 10-character name of the next block in the .TAP file, padded with trailing spaces.
Only shown in header blocks.
Data length in bytes (column "Length") for the next block in the .TAP file, as a decimal value, excluding the first 2 bytes containing the data length, the flag byte and the checksum byte.
Only shown in header blocks.
Start line if next block type is "Prog" or start (loading) address if next block type is "Code" (column "Start").
Only shown in header blocks.
Offset (column "VarStart") of variable storage area from beginning of program (only if data type is "Prog").
Only shown in header blocks.
Name of array variable in column "VarN" (only if block type is "NArr" or "CArr").
Only shown in header blocks.

This is an example of .TAP file containing character and numeric arrays; note how the "VarN" column contains the name of the array variable which in Spectrum BASIC is a single character, in this case "h" and "j":

.TAP files contain data transferred from Spectrum audio waveforms (originally recorded on audio tape) generated by ZX Spectrum compatible computers.
Spectrum audio data is organized in blocks, each block being recorded in one continuous waveform on magnetic tape. There are two types of blocks:

Header blocks: they have a fixed length (21 bytes) and a predefined structure which stores information about the immediately following data block recorded on tape (data type, name, length, start address etc.)
Data blocks: they have a simpler structure: 2 bytes representing the length of data following in the block, a flag byte, the actual data (of any size between 1 and 65535 bytes) and a checksum byte. If such a data block is not preceded by an header describing its name, type, size, start address, no other information can be known about it, except its length and flag byte. The loading address, start address, name are unknown. A block like this is called "headerless", and is supposed to be loaded at the correct address by some previously loaded code in execution at that point. Headerless blocks will be listed by this command as such.

All standard data blocks in a .TAP file (preceded by a header block) can be transferred to a DEVIL floppy image. Furthermore, headerless blocks can also be transferred, if they have a flag byte value of 0xFF, and they immediately follow a standard data block (Program, Code, Character Array or Numeric Array).

When headerless blocks are transfered to floppy, they are attached to the catalog entry created for the standard data block (Program, Code, Character Array or Numeric Array) preceding them. Looking at the 2 snapshots above, the one on the right (verbose mode) shows the standard "Code" type block named "mlobj", which requires 1 track when stored on floppy disk, followed by 11 headerless blocks, all transferable to disk. Each headerless block shows an "updated" number of required tracks for "mlobj" plus all headerless blocks up to the current one. The total number of disk tracks required to store "mlobj" plus all 11 headerless blocks, is the number shown for the last headerless block, which is 8. Also, if you watch the D# column, all these blocks (including "mlobj") have the same disk order number, which is 0001, meaning all will be stored as one DEVIL catalog entry.

There is a limit of maximum 117 headerless blocks that can be attached to a DEVIL catalog entry, which comes from the fact that all directory entries (256-byte sectors) associated to a catalog entry must be identical (except for the first byte, which is 0x00 for the first dir entry and 0xE4 for all others) and in each of them, if headerless blocks are attached, they must have their lengths stored in bytes 22 to 255 (2 bytes for the length of each headerless block, (255-21)/2=117 ).

If a standard block in a .TAP file (Program, Code, Character Array or Numeric Array) is followed by more than 117 headerless blocks, starting from the 118th on they can not be transferred to disk.

When listing contents of a .TAP file, if headerless blocks can be transferred to DEVIL floppy, they will be listed as "writable". If any headerless block cannot be transferred, it will be listed as "non-writ".

If a .TAP file contains any non-transferable headerless blocks, you will not be able to insert the contents of this .TAP file into a DEVIL floppy image, unless the non-transferable headerless blocks are deleted from the .TAP file or header blocks are created for each of them and inserted in the .TAP file in the proper positions.

NOTE:

Transferring a program containing headerless blocks to a DEVIL floppy image does not necessarily mean the program will actually run correctly in DEVIL. Some programs work, some don't, since DEVIL is not 100% compatible with the original Spectrum BASIC. An example of such program that runs correctly is "JOE BLADE", found on the GAMES2.img floppy image in my DEVIL disk archive.

GUI DESCRIPTION

When first started, the GUI will look as shown in the snapshot on the left. Note that most of the buttons will be disabled. After a floppy image or a .TAP file has been opened, the contents of it will be displayed in the list and an info box will be displayed below the list, as shown in the next snapshots. Depending on the number of elements selected in the list, some or all of the "File" menu items and of the buttons will be activated.

GUI at startup.	GUI with a floppy image loaded.

After a .TAP file has been opened, the contents of it will be displayed in the list and a .TAP file info box will be displayed below the list, as shown in the snapshot below.

GUI with .TAP file open in normal mode.	GUI with .TAP file open in verbose mode.

Tool tips are displayed when hovering the mouse over the buttons, checkboxes and status bar fields.
A built-in help (this help) is available at any time, from the menu at the top or by pressing the F1 key. Also all GUI commands are available either by selecting them from the "File" menu at the top or by clicking on the appropriate button on the right side.

The status bar has 3 fields which are used as shown in the snapshots below:

Status bar fields with floppy images.	Status bar fields with .TAP files.

If a floppy image is open: The leftmost status bar field displays the number of catalog entries selected in the list versus the number of continuous selection ranges. The second displays two values: the exact size of selected files (in bytes) versus their occupied disk size (multiple of the block size, which is 9KB). The last displays status messages after certain operations.	If a .TAP file is open: The leftmost status bar field displays the number of tape data blocks selected in the list. The second displays the start address of the block (hex offset from the beginning of file). This is only displayed if exactly one file is selected. The last displays status messages after certain operations.

The file list supports multiple selection - without having to hold down Ctrl or Shift keys while clicking with the mouse. Simply click all files you want to select, either one at a time or hold the left mouse button pressed and drag up or down to select an entire range of files.

Under the button column, there are 4 checkboxes:

"Verbose operation" - does the same thing as the "-ver" command line option
"Save operation log" - does the same thing as the "-log" command line option
"Debug mode" - does the same thing as the "-deb" command line option
"Legend" - shows or hides the info box

GUI COMMAND DESCRIPTIONS

OPEN FLOPPY IMAGE

This command is available by clicking the "Open Floppy Image" button or selecting "File->Open Floppy Image" from the menu.

A file open dialog will pop up and you can select any file having the ".img" extension. No other file extension is accepted by this program (not even ".IMG"). After the floppy image file has been successfully opened, the window title bar will display the image file name, the file list will display the DEVIL catalog of the floppy image and an info box will be shown under the file list containing the DEVIL disk information, including the disk free space fragmentation.

Click the "Open Floppy Image" button, the "File Open" dialog shows up. Select a floppy image file and click "Open"	The list shows the floppy image contents.

CREATE EMPTY FLOPPY IMAGE

This command is available by clicking the "New Floppy Image" button or selecting "File->New Floppy Image" from the menu.

This creates an empty DEVIL floppy image. Obviously, no floppy image needs to be currently open for this command to be executed.

First, a dialog is shown to choose the saving directory. Then, another dialog is shown to specify a file name for the floppy image being created. The ".img" extension is added automatically, only the actual file name must be entered.

Click the "New Floppy Image" button.	A dialog is shown to choose a directory to save the image.

Next another dialog to enter the new floppy image name (the ".img" extension is added automatically)	The new floppy image is saved.

EXTRACT DEVIL CATALOG ENTRIES FROM FLOPPY IMAGE

Catalog entries from a DEVIL floppy image can be extracted to a new .TAP file which is saved to the Linux filesystem.
This command is available by clicking the "Extract To .TAP" button or selecting "File->Extract To .TAP" from the menu, only when a floppy image is currently open.

Selected catalog entries will be saved as a single .TAP file with a name you choose, in a directory you choose. A directory selection dialog allows choosing a location where a subdirectory named after the floppy image will be created. In this subdirectory, the .TAP file containing the selected DEVIL catalog entries will be saved.

Select catalog entries and click the "Extract To .TAP" button.	Then select the target directory and click Choose.

Enter a name for the .TAP file. The ".tap" extension will be added automatically.	Status bar message confirming extraction.

The .TAP file is saved in the destination directory.

ADD (INSERT) DEVIL CATALOG ENTRIES TO FLOPPY IMAGE

New catalog entries can be inserted in the DEVIL catalog from an existing .TAP file.
This command is available by clicking the "Insert From .TAP" button or selecting "File->Insert From .TAP" from the menu, only when a floppy image is currently open.

A file select dialog will pop up, allowing the selection of a single .TAP file having the ".tap" extension. No other file extension is accepted by this program (not even ".TAP").

The entire contents of the .TAP file will be transferred to the floppy image, but only IF A BIG ENOUGH CONTINUOUS FREE SPACE is found on the floppy image. Otherwise an error message will be shown and the operation will be aborted.

In the example below, an empty floppy image "TESTDISK.img" is opened. Then the "Insert From .TAP" command is launched and the "Dragon's Lair.tap" file is selected and then written into the floppy image. Then the updated floppy image contents is shown in the list of catalog items.

With a floppy image loaded, click the "Insert From .TAP" button. For this example, we use an empty floppy image.	Then select a .TAP file.

The contents of the .TAP file is inserted in the DEVIL catalog.

RENAME ONE DEVIL CATALOG ENTRY IN A FLOPPY IMAGE

This command is available by clicking the "Rename Cat. Entry" button or selecting "File->Rename Cat. Entry" from the menu. This command is only available if a floppy image is currently open and exactly one catalog entry is selected in the list. The entry selected must not be a headerless block.

A dialog will pop up, where the name of the selected entry can be changed.

With a floppy image loaded, select one catalog entry and then click the "Rename Cat. Entry" button.	Then change the entry name and click OK. In this example, we rename "3D GAME" to "3D Game".

The list is updated and shows the renamed catalog entry.

DELETE DEVIL CATALOG ENTRIES FROM FLOPPY IMAGE

This command is available by clicking the "Delete Cat. Entries" button or selecting "File->Delete Cat. Entries" from the menu. This command is only available if a floppy image is currently open and at least one CP/M file is selected in the list.

After a confirmation prompt, all selected catalog entries in the list will be deleted from the currently open floppy image. The deletion is total, all blocks allocated to the deleted files will be overwritten with the E5 byte as well as all their directory entries. Once deleted, files cannot be recovered. Furthermore, after deletion the free space will be automatically defragmented, which can be seen in the disk space allocation map in the info box below the list of catalog entries.

With a floppy image loaded, select some catalog entries and then click the "Delete Cat. Entries" button.	A confirmation prompt is shown. Click Yes to delete the entries.

The entries are deleted.
The GUI is updated with the new catalog contents.

CHANGE ATTRIBUTES OF CATALOG ENTRIES ON FLOPPY IMAGE

This command is available by clicking the "Change Attributes" button or selecting "File->Change Attributes" from the menu. This command is only available if a floppy image is currently open and at least one catalog entry is selected in the list.

A dialog will pop up where attributes can be changed for all selected catalog entries in the list (all selected entries will have the same attributes).
There are 2 attributes that can be manipulated here: the R/O-R/W attribute and the DIR-SYS attribute.

With a floppy image loaded, select catalog entries and then click the "Change Attributes" button.	A dialog is shown to change attributes.

After clicking "OK", the list shows the entries with the updated attributes.

INTERLEAVE A NON-INTERLEAVED FLOPPY IMAGE

This command is available by clicking the "Interleave Image" button or selecting "File->Interleave Image" from the menu. There is no need to have a floppy image loaded for this command to be available.

The purpose is to convert a (non-interleaved) RAW floppy image saved by other imaging software (such as the HxC Emulator Software) to the (interleaved) format used by this utility.

The source file (deinterleaved floppy image) must have a ".dimg" extension. The result will be saved in a directory of your choice with the same name but an ".img" extension.

Click the "Interleave Image" button.	A dialog is shown to select the non-interleaved image.

Next another dialog is shown to select the target directory.	The interleaved floppy image is saved with the same name and an .img extension.

DE-INTERLEAVE AN INTERLEAVED FLOPPY IMAGE

This command is available by clicking the "De-Interleave Image" button or selecting "File->De-Interleave Image" from the menu. This command is only available when a floppy image is open.

The purpose is to convert the currently open floppy image to a non-interleaved format accepted by other software, such as the HxC Emulator Software. The result will be saved in a directory of your choice with the same name but a ".dimg" extension.

With a floppy image loaded, click the "De-Interleave Image" button.	A dialog is shown to choose the target directory.

After clicking Choose, the deinterleaved image is saved.	The target directory contains the deinterleaved image.

OPEN .TAP FILE

This command is available by clicking the "Open .TAP File" button or selecting "File->Open .TAP File" from the menu.

A file open dialog will pop up and you can select any file having the ".tap" extension. No other file extension is accepted by this program (not even ".TAP"). After the floppy image file has been successfully opened, the window title bar will display the .TAP file name, the file list will display the contents of the .TAP file and an info box will be shown under the file list containing a description of the column names used by the list of items. This info box can be hidden by unchecking the "Legend" checkbox.

Click the "Open .TAP File" button, the "File Open" dialog shows up.	GUI with .TAP file open.

The example above shows a .TAP file containing headerless blocks with a flag byte (0x98) different than 0xFF, therefore not transferable to a DEVIL floppy image. These blocks will be listed as "non-writ".

GUI with info box hidden.	GUI with another .TAP file open.

The example above shows another .TAP file containing headerless blocks with a flag byte of 0xFF, this time transferable to a DEVIL floppy image. These blocks will be listed as "writable".

Also, below is an example of .TAP file containing data arrays (numeric and character arrays).

GUI with .TAP file open containing arrays.	GUI with corrupted .TAP file open.

Normally, the "E" column will be empty, but if the .TAP file is corrupted, certain symbols will be shown in this column to signal different types of errors encountered while reading the .TAP file data blocks. The example above (right) shows what happens when opening the same .TAP file on the left, but with the last 10 bytes missing. The description for all possible error symbols is given in the info box.

CREATE .TAP FILE FROM BINARY FILE

This command is available by clicking the "New .TAP File" button or selecting "File->New .TAP File" from the menu. It allows creating a new .TAP file with one single headerless data block, with a flag byte of any value you choose (00-FF), containing binary data read from any user-selected binary file (.bin). Once the .TAP file has been generated (if the flag byte value chosen was FF), the user can generate a standard header block for the headerless block previously created. This way, new .TAP files can be created containing any number of data blocks of any type.

A file open dialog will pop up and you can select any binary file having the ".bin" extension (all lowercase). No other file extension is accepted by this program (not even ".BIN").

Then another dialog will be shown where you must enter a 2-digit hex value for the flag byte of the new .TAP data block. If you choose FF, you will later be able to create a standard header for this data block.

Click the "New .TAP File" button.	Select a binary file containing data for a new .TAP data block.

Finally a File Save dialog will be shown, asking for a name for the new .TAP file being created. Navigate to a directory where you want the file to be saved and then choose a file name for the new .TAP file. If you don't manually enter the ".tap" extension, it will be added automatically.

Select a flag byte for the new .TAP data block.	Enter a name for the new .TAP file (".tap" extension is added automatically.

The new .TAP file is saved.

EXTRACT DATA BLOCK FROM .TAP FILE

This command is available by clicking the "Extract to .BIN" button or selecting "File->Extract to .BIN" from the menu, when a .TAP file is loaded. It extracts the data from one single data block selected in the currently open .TAP file. This command is only available if a .TAP file is currently open and exactly one data block is selected in the list.

With a .TAP file loaded, select exactly one data block and click "Extract to .BIN".	Select a target directory.

Select a name for the new binary file and click "OK".	The new binary file is saved.

ADD (INSERT) DATA BLOCK TO .TAP FILE

This command is available by clicking the "Insert from .TAP/.BIN" button or selecting "File->Insert from .TAP/.BIN" from the menu. This command is only available if a .TAP file is currently open and either zero or exactly one data block is selected in the list.

This command will insert one or more data blocks in the currently open .TAP file, from another .TAP file or a binary file (.BIN). The command behaves differently depending on whether or not a data block of the currently open .TAP file is selected in the list:

1. If NO data block is selected in the list before this command is launched, the new data block(s) will be APPENDED AT THE END of the currently open .TAP file.

2. If ONE data block is selected in the list before this command is launched, the new data block(s) will be INSERTED BEFORE the selected data block.

Example of APPENDING new data blocks to the currently open .TAP file, from another .TAP file:

With a .TAP file open and no selection, click the "Insert from .TAP/.BIN" button.	Select "Insert from .TAP file" and click "OK".

Choose a .TAP file to insert data blocks from and click "OK".	The new data blocks are APPENDED at the end of the currently open .TAP file.

Example of INSERTING new data blocks into the currently open .TAP file, from another .TAP file:

With a .TAP file open and ONE block selected, click the "Insert from .TAP/.BIN" button.	Select "Insert from .TAP file" and click "OK".

Choose a .TAP file to insert data blocks from and click "OK".	The new data blocks are INSERTED before the previously selected block in the currently open .TAP file.

Appending/inserting from a .BIN file works identically, except you need to select "Insert from .BIN file" instead of "Insert from .TAP file" and then choose a .BIN file instead of a .TAP file. The .BIN file must have a size of max. 64 KB and only one new block will be added.

Additionally, you will need to enter a 2-digit hex value for the flag byte of the new data block added to the currently open .TAP file.

Example of APPENDING a data block to the currently open .TAP file, from a binary file:

With a .TAP file open and no selection, click the "Insert from .TAP/.BIN" button.	Select "Insert from .BIN file" and click "OK".

Choose a .BIN file to insert a data block from and click "OK".	Enter a 2-digit hex value for the flag byte of the new block.

The new data block is APPENDED at the end of the currently open .TAP file.

Example of INSERTING a data block into the currently open .TAP file, from a binary file:

With a .TAP file open and ONE block selected, click the "Insert from .TAP/.BIN" button.	Select "Insert from .BIN file" and click "OK".

Choose a .BIN file to insert a data block from and click "OK".	Enter a 2-digit hex value for the flag byte of the new block.

The new data block is INSERTED before the previously selected block,
in the currently open .TAP file.

RENAME HEADER BLOCK IN .TAP FILE

This command is available by clicking the "Rename Header" button or selecting "File->Rename Header" from the menu. This command is only available if a .TAP file is currently open and exactly one data block of "Header" type (Form="Head", Flag=00h, Size=19h) is selected in the list.

This command allows changing the name stored in the header block.

With a .TAP file open and ONE header block selected, click the "Rename Header" button.	A "Rename" dialog shows up, pre-filled with the current name stored in the header.

Change the current name to a new name and click "OK".	The list is updated with the new name stored in the header block.

DELETE DATA BLOCK FROM .TAP FILE

This command is available by clicking the "Delete Block" button or selecting "File->Delete Block" from the menu. This command is only available if a .TAP file is currently open and exactly one data block is selected in the list.

This command deletes the block selected in the list.

With a .TAP file open and ONE block selected, click the "Delete Block" button.	A confirmation dialog shows up, click "Yes" to proceed.

The data block is deleted and the list updated.

CREATE HEADER FOR A HEADERLESS DATA BLOCK IN .TAP FILE

This command is available by clicking the "Create Header" button or selecting "File->Create Header" from the menu. This command is only available if a .TAP file is currently open and exactly one headerless data block with a FFh flag byte is selected in the list.

This command allows creating a standard header block matching the parameters of the selected headerless block. The header block will be generated as for a "bytes" type of data (Type="Code") and will be placed right before the headerless block, so that in the end the headerless block will become a standard "Code" data block.

With a .TAP file open and ONE headerless block selected, click the "Create Header" button.	A dialog shows up, enter a name and loading address for the new header block.

The header block is created and placed in front of the headerless block,
transforming it into a "Code" block.

CoBra DEVIL raw floppy image reader / writer for LinuxCREATED BY: CoBra @ RomanianHomeComputer

CONTENTS:

STRUCTURE OF A DEVIL DISK DIRECTORY ENTRY

.TAP FILE FORMAT (USED BY ANY ZX SPECTRUM EMULATOR)

Extracting data in normal mode.

Extracting data in verbose mode.

Writing data in normal mode.

Writing data in verbose mode.

Deleting data in normal mode.

Deleting data in verbose mode.

Defragmenting data in normal mode.

Defragmenting data in verbose mode.

Attribute change in normal mode.

Attribute change in verbose mode.

Interleave command in normal mode.

Interleave command in verbose mode.

Deinterleave command in normal mode.

Deinterleave command in verbose mode.

.TAP file list command in normal mode.

.TAP file list command in verbose mode.

NOTE:

CoBra DEVIL raw floppy image reader / writer for Linux
CREATED BY: CoBra @ RomanianHomeComputer